<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Create a new ReadPreference</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="mongodb-driver-readpreference.bsonserialize.html">« MongoDB\Driver\ReadPreference::bsonSerialize</a></li>
      <li style="float: right;"><a href="mongodb-driver-readpreference.gethedge.html">MongoDB\Driver\ReadPreference::getHedge »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="class.mongodb-driver-readpreference.html">MongoDB\Driver\ReadPreference</a></li>
    <li>Create a new ReadPreference</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="mongodb-driver-readpreference.construct" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">MongoDB\Driver\ReadPreference::__construct</h1>
  <p class="verinfo">(mongodb &gt;=1.0.0)</p><p class="refpurpose"><span class="refname">MongoDB\Driver\ReadPreference::__construct</span> &mdash; <span class="dc-title">Create a new ReadPreference</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-mongodb-driver-readpreference.construct-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="modifier">final</span> <span class="modifier">public</span> <span class="methodname"><strong>MongoDB\Driver\ReadPreference::__construct</strong></span>(<span class="methodparam"><span class="type"><span class="type">string</span>|<span class="type">int</span></span> <code class="parameter">$mode</code></span>, <span class="methodparam"><span class="type">?</span><span class="type"><span class="type">array</span><span class="type"></span></span> <code class="parameter">$tagSets</code><span class="initializer"> = <strong><code>null</code></strong></span></span>, <span class="methodparam"><span class="type">?</span><span class="type"><span class="type">array</span><span class="type"></span></span> <code class="parameter">$options</code><span class="initializer"> = <strong><code>null</code></strong></span></span>)</div>

  <p class="para rdfs-comment">
   Constructs a new <span class="classname"><a href="class.mongodb-driver-readpreference.html" class="classname">MongoDB\Driver\ReadPreference</a></span>, which
   is an immutable value object.
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-mongodb-driver-readpreference.construct-parameters">
  <h3 class="title">参数</h3>
  <dl>
   
    <dt>
<code class="parameter">mode</code></dt>

    <dd>

     <p class="para">
      <table class="doctable table">
       <caption><strong>Read preference mode</strong></caption>
       
        <thead>
         <tr>
          <th>Value</th>
          <th>Description</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td><strong><code>MongoDB\Driver\ReadPreference::RP_PRIMARY</code></strong> or <code class="literal">&quot;primary&quot;</code></td>
          <td>
           <p class="para">
            All operations read from the current replica set primary. This is
            the default read preference for MongoDB.
           </p>
          </td>
         </tr>

         <tr>
          <td><strong><code>MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED</code></strong> or <code class="literal">&quot;primaryPreferred&quot;</code></td>
          <td>
           <p class="para">
            In most situations, operations read from the primary but if it is
            unavailable, operations read from secondary members.
           </p>
          </td>
         </tr>

         <tr>
          <td><strong><code>MongoDB\Driver\ReadPreference::RP_SECONDARY</code></strong> or <code class="literal">&quot;secondary&quot;</code></td>
          <td>
           <p class="para">
            All operations read from the secondary members of the replica set.
           </p>
          </td>
         </tr>

         <tr>
          <td><strong><code>MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED</code></strong> or <code class="literal">&quot;secondaryPreferred&quot;</code></td>
          <td>
           <p class="para">
            In most situations, operations read from secondary members but if no
            secondary members are available, operations read from the primary.
           </p>
          </td>
         </tr>

         <tr>
          <td><strong><code>MongoDB\Driver\ReadPreference::RP_NEAREST</code></strong> or <code class="literal">&quot;nearest&quot;</code></td>
          <td>
           <p class="para">
            Operations read from member of the replica set with the least
            network latency, irrespective of the member&#039;s type.
           </p>
          </td>
         </tr>

        </tbody>
       
      </table>

     </p>
    </dd>

   
   
    <dt>
<code class="parameter">tagSets</code></dt>

    <dd>

     <p class="para">
      Tag sets allow you to target read operations to specific members of a
      replica set. This parameter should be an array of associative arrays, each
      of which contain zero or more key/value pairs. When selecting a server for
      a read operation, the driver attempt to select a node having all tags in a
      set (i.e. the associative array of key/value pairs). If selection fails,
      the driver will attempt subsequent sets. An empty tag set
      (<code class="literal">array()</code>) will match any node and may be used as a
      fallback.
     </p>
     <p class="para">
      Tags are not compatible with the
      <strong><code>MongoDB\Driver\ReadPreference::RP_PRIMARY</code></strong> mode and,
      in general, only apply when selecting a secondary member of a set for a
      read operation. However, the
      <strong><code>MongoDB\Driver\ReadPreference::RP_NEAREST</code></strong> mode, when
      combined with a tag set, selects the matching member with the lowest
      network latency. This member may be a primary or secondary.
     </p>
    </dd>

   
   
    <dt>
<code class="parameter">options</code></dt>

    <dd>

     <p class="para">
      <table class="doctable table">
       <caption><strong>options</strong></caption>
       
        <thead>
         <tr>
          <th>Option</th>
          <th>Type</th>
          <th>Description</th>
         </tr>

        </thead>

        <tbody class="tbody">
         <tr>
          <td>hedge</td>
          <td><span class="type"><span class="type">object</span>|<span class="type">array</span></span></td>
          <td>
           <p class="para">Specifies whether to use <a href="https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router/#mongos-hedged-reads" class="link external">&raquo;&nbsp;hedged reads</a>, which are supported by MongoDB 4.4+ for sharded queries.</p>
           <p class="para">
            Server hedged reads are available for all non-primary read preferences
            and are enabled by default when using the <code class="literal">&quot;nearest&quot;</code>
            mode. This option allows explicitly enabling server hedged reads for
            non-primary read preferences by specifying
            <code class="literal">[&#039;enabled&#039; =&gt; true]</code>, or explicitly disabling
            server hedged reads for the <code class="literal">&quot;nearest&quot;</code> read
            preference by specifying <code class="literal">[&#039;enabled&#039; =&gt; false]</code>.
           </p>
          </td>
         </tr>

         <tr>
          <td>maxStalenessSeconds</td>
          <td><span class="type">int</span></td>
          <td>
           <p class="para">
            Specifies a maximum replication lag, or &quot;staleness&quot;, for reads from
            secondaries. When a secondary&#039;s estimated staleness exceeds
            this value, the driver stops using it for read operations.
           </p>
           <p class="para">
            If specified, the max staleness must be a signed 32-bit integer
            greater than or equal to
            <strong><code>MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS</code></strong>.
           </p>
           <p class="para">
            Defaults to
            <strong><code>MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</code></strong>,
            which means that the driver will not consider a secondary&#039;s lag
            when choosing where to direct a read operation.
           </p>
           <p class="para">
            This option is not compatible with the
            <strong><code>MongoDB\Driver\ReadPreference::RP_PRIMARY</code></strong> mode.
            Specifying a max staleness also requires all MongoDB instances in
            the deployment to be using MongoDB 3.4+. An exception will be thrown
            at execution time if any MongoDB instances in the deployment are of
            an older server version.
           </p>
          </td>
         </tr>

        </tbody>
       
      </table>

     </p>
    </dd>

   
  </dl>

 </div>


 <div class="refsect1 errors" id="refsect1-mongodb-driver-readpreference.construct-errors">
  <h3 class="title">错误／异常</h3>
  <ul class="simplelist">
   <li class="member">Throws <span class="classname"><a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a></span> on argument parsing errors.</li>
   <li class="member">Throws <span class="classname"><a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a></span> if <code class="parameter">mode</code> is invalid.</li>
   <li class="member">Throws <span class="classname"><a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a></span> if <code class="parameter">tagSets</code> is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).</li>
   <li class="member">Throws <span class="classname"><a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a></span> if the <code class="literal">&quot;maxStalenessSeconds&quot;</code> option is provided for a primary read preference or is out of range.</li>
  </ul>
 </div>


 <div class="refsect1 changelog" id="refsect1-mongodb-driver-readpreference.construct-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>PECL mongodb 1.8.0</td>
       <td>
        Added the <code class="literal">&quot;hedge&quot;</code> option.
       </td>
      </tr>

      <tr>
       <td>PECL mongodb 1.3.0</td>
       <td>
        <p class="para">
         The <code class="parameter">mode</code> argument now accepts a string value,
         which is consistent with the <code class="literal">&quot;readPreference&quot;</code> URI
         option for <span class="function"><a href="mongodb-driver-manager.construct.html" class="function">MongoDB\Driver\Manager::__construct()</a></span>.
        </p>
       </td>
      </tr>

      <tr>
       <td>PECL mongodb 1.2.0</td>
       <td>
        <p class="para">
         Added a third <code class="parameter">options</code> argument, which supports
         the <code class="literal">&quot;maxStalenessSeconds&quot;</code> option.
        </p>
       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-mongodb-driver-readpreference.construct-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1327">
   <p><strong>示例 #1 <span class="function"><strong>MongoDB\Driver\ReadPreference::__construct()</strong></span> example</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br /></span><span style="color: #FF8000">/*&nbsp;Prefer&nbsp;a&nbsp;secondary&nbsp;node&nbsp;but&nbsp;fall&nbsp;back&nbsp;to&nbsp;a&nbsp;primary.&nbsp;*/<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(new&nbsp;</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">::</span><span style="color: #0000BB">RP_SECONDARY_PREFERRED</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*&nbsp;Prefer&nbsp;a&nbsp;node&nbsp;in&nbsp;the&nbsp;New&nbsp;York&nbsp;data&nbsp;center&nbsp;with&nbsp;lowest&nbsp;latency.&nbsp;*/<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(new&nbsp;</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">::</span><span style="color: #0000BB">RP_NEAREST</span><span style="color: #007700">,&nbsp;[[</span><span style="color: #DD0000">'dc'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">'ny'</span><span style="color: #007700">]]));<br /><br /></span><span style="color: #FF8000">/*&nbsp;Require&nbsp;a&nbsp;secondary&nbsp;node&nbsp;whose&nbsp;replication&nbsp;lag&nbsp;is&nbsp;within&nbsp;two&nbsp;minutes&nbsp;of&nbsp;the&nbsp;primary&nbsp;*/<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(new&nbsp;</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">::</span><span style="color: #0000BB">RP_SECONDARY</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">null</span><span style="color: #007700">,&nbsp;[</span><span style="color: #DD0000">'maxStalenessSeconds'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">120</span><span style="color: #007700">]));<br /><br /></span><span style="color: #FF8000">/*&nbsp;Explicitly&nbsp;enable&nbsp;server&nbsp;hedged&nbsp;reads&nbsp;*/<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(new&nbsp;</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">ReadPreference</span><span style="color: #007700">::</span><span style="color: #0000BB">RP_SECONDARY</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">null</span><span style="color: #007700">,&nbsp;[</span><span style="color: #DD0000">'hedge'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;[</span><span style="color: #DD0000">'enabled'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">true</span><span style="color: #007700">]]));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>以上例程会输出：</p></div>
   <div class="example-contents screen">
<div class="cdata"><pre>
object(MongoDB\Driver\ReadPreference)#1 (1) {
  [&quot;mode&quot;]=&gt;
  string(18) &quot;secondaryPreferred&quot;
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  [&quot;mode&quot;]=&gt;
  string(7) &quot;nearest&quot;
  [&quot;tags&quot;]=&gt;
  array(1) {
    [0]=&gt;
    object(stdClass)#2 (1) {
      [&quot;dc&quot;]=&gt;
      string(2) &quot;ny&quot;
    }
  }
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  [&quot;mode&quot;]=&gt;
  string(9) &quot;secondary&quot;
  [&quot;maxStalenessSeconds&quot;]=&gt;
  int(120)
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  [&quot;mode&quot;]=&gt;
  string(9) &quot;secondary&quot;
  [&quot;hedge&quot;]=&gt;
  object(stdClass)#1 (1) {
    [&quot;enabled&quot;]=&gt;
    bool(true)
  }
}
</pre></div>
   </div>
  </div>
 </div>



 <div class="refsect1 seealso" id="refsect1-mongodb-driver-readpreference.construct-seealso">
  <h3 class="title">参见</h3>
  <ul class="simplelist">
   <li class="member"><a href="https://www.mongodb.com/docs/manual/core/read-preference/" class="link external">&raquo;&nbsp;Read Preference reference</a></li>
  </ul>
 </div>


</div></div></div></body></html>